feat: Add the override store, overlay, and data system wiring by kinyoklion · Pull Request #527 · launchdarkly/python-server-sdk

kinyoklion · 2026-09-25T22:13:20Z

Summary

This is the third step of the flag overrides port described by the OVERRIDE specification. It is based on the model marker branch because the phases are stacked; retarget to feat/overrides once that branch merges.

The override layer (ldclient/impl/overrides). OverrideLayer is the override store: it holds marked shallow copies of the flag and segment definitions a source supplies, keyed by key, and is replaced wholesale on each update, so the layer's contents are exactly one snapshot at any instant and an empty snapshot clears it. Dictionaries are decoded with the model constructors, and an invalid definition raises rather than being defaulted. A definition whose key differs from its key in the snapshot raises too, and the layer is left unchanged: evaluation reads an entry by its snapshot key, while the all-flags state and events use the definition's key. OverrideStoreView is the overlay at the store read boundary: a read of a flag or segment returns the override entry when one exists and the LaunchDarkly entry otherwise, whatever the state of the base store, and an enumeration is the union of both with the override entry winning, including over a deleted item. A failure of the base enumeration propagates, as it does without the overlay. When that read fails, all_flags_state logs the failure as before and, if the override layer holds flags, returns a state of those flags marked invalid rather than an empty one: overrides only add to the state, and a client-side SDK bootstrapped from it uses its flags whatever $valid says, so the overridden values still reach it. With no override flags the state is the same invalid, empty state as without a source. The sink stops accepting snapshots when the client is closed, and when the source fails to start it also clears what the source supplied. OverrideSinkImpl applies each snapshot as one serialized operation and notifies flag change listeners of every flag whose merged-view evaluation may have changed: entries added, removed, or changed, plus every flag that depends on them through prerequisites or segment references. An identical snapshot notifies nothing.

LaunchDarkly changes reach override dependents. The layer keeps a dependency graph of its entries, rebuilt on each replacement, and the store (sync and async) expands every changed LaunchDarkly item through both its own graph and the layer's, to a fixpoint. A change to a prerequisite flag or a segment that an override entry references therefore notifies that entry's flag, the same way dependent flags are notified for LaunchDarkly data, and a chain may cross between LaunchDarkly data and overrides any number of times. Without an override source the store's behavior is unchanged.

Configuration and wiring. OverrideSource and OverrideSink are public protocols in ldclient.interfaces, so a custom source can be supplied. OverrideSourceBuilder and DataSystemConfig.override_source (also on AsyncDataSystemConfig) plus ConfigBuilder.overrides(...) make the source an option of the FDv2 data system. The source is built with the data system, so invalid configuration raises from the client constructor like any other invalid component configuration. It starts before the data system's own threads and its initial load completes before the constructor returns; it is closed when the client is closed, after the sink stops accepting snapshots, and an exception from its close is logged. An exception from its start does not fail the constructor or start: the data system logs it, closes the source, clears any snapshot the source supplied before failing, and the client runs without overrides. The SDK's own file-based source does not raise from start; a custom source could. The source is not built or started when the client is offline, and the SDK logs a warning that it is not used. The data system's store becomes the overlay when a source is configured, so evaluation, prerequisite and segment resolution, and the all-flags read all see override precedence. The override source has no effect on initialization status, data availability, or data source status. The legacy FDv1 data system reports no override source. When the data system fails to start, the client constructor stops each component in turn and logs any failure to stop, so the event processor still stops and the caller receives the start failure.

The client facade. Both LDClient and AsyncLDClient consult the override layer before the not-initialized short-circuit: an overridden flag is served before the client has LaunchDarkly data, and a flag the layer does not hold takes exactly the path it took before this feature, so a configured but empty source changes nothing with the same warning and event as before. The all-flags state reads through the overlay. While the client has no LaunchDarkly data it contains only the flags the layer holds, read from the layer rather than the overlay so that LaunchDarkly data in a store without an init marker stays out (with a once-per-client warning), and it is invalid when the layer holds no flags. Without a source this state is empty, because the SDK reports no flags before the store is initialized, so the override flags only add to what it reports; overrides never remove a flag from the state. An evaluation that fails with an unexpected exception reports the EXCEPTION reason with overrideAffected when the flag came from the override layer, in a single evaluation and in the all-flags state (OVERRIDE 1.5.4); the marker is read through is_override_definition, so the error path cannot fail on an unexpected store item. On the async client, override change notifications are marshalled onto the event loop, like every other change notification.

The async client with a persistent store. The async client works out which flags an override change affects from the in-memory store, the only store it can read synchronously (async_fdv2.py). While a persistent store is the active store, a change to an override notifies the overridden flags, but not LaunchDarkly flags that depend on them through a prerequisite or a segment. The documentation of AsyncDataSystemConfig.override_source says so.

Left to later PRs in the stack.

all_flags_state still keeps trackEvents, trackReason and debugEventsUntilDate for override-affected flags (OVERRIDE 1.4.1.1). The events step, feat: Mark override-affected evaluations in analytics events #528, clears them.
An override entry marked as deleted is rejected by fix: Reject deleted flags and segments in flag overrides #574, which is stacked on top of the stack (launchdarkly/sdk-specs#288).

Tests. Unit tests for the layer, overlay (sync and async), and sink; client tests for the gate, source lifecycle, construction errors, offline, precedence, prerequisite and segment overrides, all-flags state, and flag change and flag value change listeners, for both clients; and a runner for the OVERRIDE specification test vectors (ldclient/testing/testdata/override-vectors/vectors.json) through the full client stack. The vector runner's per-evaluation summary marker assertion is added with the events step.

SDK-3250

Note

Overview
Adds experimental flag/segment overrides that can take precedence over LaunchDarkly data at evaluation time, wired through FDv2 (sync and async).

Configuration: Optional override_source on the data system (ConfigBuilder.overrides(...), OverrideSourceBuilder, public OverrideSource / OverrideSink protocols). Offline clients skip building/starting the source.

Runtime: An OverrideLayer holds snapshot replacements; OverrideStoreView overlays the feature store so per-key reads prefer overrides; OverrideSinkImpl applies updates and fans out flag change notifications via merged-view dependency diffing. The store can register the layer as external dependencies so LaunchDarkly prerequisite/segment updates also notify affected override flags.

Clients: LDClient / AsyncLDClient read the override layer before the not-initialized default path and adjust all_flags_state to return override-only bootstrapping when LD data is unavailable (with once-per-client warnings). Evaluation errors set overrideAffected when the definition came from overrides. Sync client rolls back components if data system start fails.

Tests: Layer/overlay/sink units, broad sync+async client scenarios, store cross-graph notification, and OVERRIDE spec vectors (override-vectors/vectors.json).

^{Reviewed by Cursor Bugbot for commit 0489514. Bugbot is set up for automated code reviews on this repo. Configure here.}

_{Opened from termag}

kinyoklion · 2026-10-03T01:23:42Z

bugbot review

cursor